package com.aleyn.annotation

import kotlin.reflect.KClass

/**
 * @author: Aleyn
 * @date: 2023/7/28 11:28
 *
 * 单例模式（Singleton）依赖注入注解。
 *
 * 此注解用于标记一个类，表示该类由 LRouter 的依赖注入容器管理，并且在整个应用生命周期中
 * **只会存在一个**实例。这是实现全局共享状态或资源的常用方式。
 *
 * 使用示例：
 * ```kotlin
 * // 将 UserRepositoryImpl 标记为单例。应用中所有请求 UserRepositoryImpl 的地方都会得到同一个实例。
 * @Singleton
 * class UserRepositoryImpl : UserRepository { ... }
 *
 * // 将实现类 ApiServiceImpl 绑定到 ApiService 接口，并标记为单例
 * // 当请求 ApiService 类型的实例时，容器会返回唯一的 ApiServiceImpl 实例
 * @Singleton(bind = ApiService::class)
 * class ApiServiceImpl : ApiService { ... }
 *
 * // 标记为非懒加载的单例，应用启动时就会被创建
 * @Singleton(lazy = false)
 * class AppManager { ... }
 * ```
 *
 * @param bind 可选参数，用于将当前实现类绑定到一个特定的父类或接口。
 *             当指定了 `bind` 类型后，你可以通过请求 `bind` 指定的类型来获取当前类的单例实例。
 *             这在面向接口编程时非常有用。如果未指定，则默认绑定到当前类自身。
 *             `Unit::class` 是一个占位符，表示未指定绑定类型。
 * @param lazy 是否采用懒加载模式。默认为 `true`，表示只有在第一次请求该实例时，容器才会创建它。
 *             如果设置为 `false`，该实例将在 LRouter 初始化时被立即创建。
 *             对于一些需要在应用启动后尽快准备就绪的服务，可以设置为 `false`。
 */
@Retention(AnnotationRetention.SOURCE)
@Target(AnnotationTarget.CLASS)
annotation class Singleton(
    val bind: KClass<*> = Unit::class,
    val lazy: Boolean = true
)

